WebCodecs VideoFrame 평면 접근: 원시 비디오 데이터 조작 심층 분석

수년간 웹 브라우저에서의 고성능 비디오 처리는 먼 꿈처럼 느껴졌습니다. 개발자들은 종종 <video> 요소와 2D Canvas API의 한계에 갇혀 있었는데, 이 기술들은 강력하긴 하지만 성능 병목 현상을 유발하고 기저의 원시 비디오 데이터에 대한 접근을 제한했습니다. WebCodecs API의 등장은 이러한 환경을 근본적으로 바꾸어, 브라우저에 내장된 미디어 코덱에 대한 저수준 접근을 제공합니다. 이 API의 가장 혁신적인 기능 중 하나는 VideoFrame 객체를 통해 개별 비디오 프레임의 원시 데이터에 직접 접근하고 조작할 수 있는 능력입니다.

이 글은 단순한 비디오 재생을 넘어 더 나아가고자 하는 개발자들을 위한 종합 가이드입니다. 우리는 VideoFrame 평면 접근의 복잡성을 탐구하고, 색 공간 및 메모리 레이아웃과 같은 개념을 명확히 설명하며, 실시간 필터부터 정교한 컴퓨터 비전 작업에 이르기까지 차세대 인브라우저 비디오 애플리케이션을 구축할 수 있도록 실용적인 예제를 제공할 것입니다.

사전 요구 사항

이 가이드를 최대한 활용하려면 다음에 대한 확실한 이해가 필요합니다:

• 최신 자바스크립트: 비동기 프로그래밍(async/await, Promises)을 포함합니다.
• 기본적인 비디오 개념: 프레임, 해상도, 코덱과 같은 용어에 익숙하면 도움이 됩니다.
• 브라우저 API: Canvas 2D나 WebGL과 같은 API 사용 경험이 있으면 유용하지만, 필수 사항은 아닙니다.

비디오 프레임, 색 공간, 그리고 평면 이해하기

API에 대해 알아보기 전에, 비디오 프레임 데이터가 실제로 어떻게 생겼는지에 대한 견고한 정신 모델을 구축해야 합니다. 디지털 비디오는 정지된 이미지, 즉 프레임의 연속입니다. 각 프레임은 픽셀의 그리드이며, 각 픽셀은 색상을 가집니다. 그 색상이 어떻게 저장되는지는 색 공간과 픽셀 형식에 의해 정의됩니다.

RGBA: 웹의 기본 언어

대부분의 웹 개발자들은 RGBA 색상 모델에 익숙합니다. 각 픽셀은 빨강(Red), 초록(Green), 파랑(Blue), 그리고 알파(Alpha, 투명도)의 네 가지 구성 요소로 표현됩니다. 데이터는 일반적으로 메모리에 인터리브(interleaved) 방식으로 저장되는데, 이는 단일 픽셀에 대한 R, G, B, A 값이 연속적으로 저장된다는 의미입니다:

[R1, G1, B1, A1, R2, G2, B2, A2, ...]

이 모델에서 전체 이미지는 단일의 연속적인 메모리 블록에 저장됩니다. 이를 단일 "평면(plane)"의 데이터를 갖는 것으로 생각할 수 있습니다.

YUV: 비디오 압축의 언어

그러나 비디오 코덱은 거의 RGBA를 직접 다루지 않습니다. 그들은 YUV(더 정확하게는 Y'CbCr) 색 공간을 선호합니다. 이 모델은 이미지 정보를 다음과 같이 분리합니다:

• Y (휘도): 밝기 또는 흑백 정보. 사람의 눈은 휘도 변화에 가장 민감합니다.
• U (Cb) 및 V (Cr): 색차 또는 색상-차이 정보. 사람의 눈은 밝기 디테일보다 색상 디테일에 덜 민감합니다.

이러한 분리는 효율적인 압축의 핵심입니다. U와 V 구성 요소의 해상도를 줄이는 기술인 크로마 서브샘플링(chroma subsampling)을 통해, 우리는 인지할 수 있는 품질 손실을 최소화하면서 파일 크기를 크게 줄일 수 있습니다. 이는 Y, U, V 구성 요소가 별도의 메모리 블록, 즉 "평면"에 저장되는 평면(planar) 픽셀 형식으로 이어집니다.

일반적인 형식은 I420(YUV 4:2:0의 한 종류)으로, 2x2 픽셀 블록마다 4개의 Y 샘플이 있지만 U와 V 샘플은 각각 하나씩만 있습니다. 이는 U와 V 평면이 Y 평면의 너비와 높이의 절반을 가짐을 의미합니다.

이 차이점을 이해하는 것은 매우 중요합니다. 왜냐하면 WebCodecs는 디코더가 제공하는 바로 이 평면들에 대한 직접적인 접근을 제공하기 때문입니다.

VideoFrame 객체: 픽셀 데이터로의 관문

이 퍼즐의 중심 조각은 VideoFrame 객체입니다. 이것은 비디오의 단일 프레임을 나타내며 픽셀 데이터뿐만 아니라 중요한 메타데이터도 포함합니다.

VideoFrame의 주요 속성

• format: 픽셀 형식(예: 'I420', 'NV12', 'RGBA')을 나타내는 문자열입니다.
• codedWidth / codedHeight: 코덱에서 요구하는 패딩을 포함하여 메모리에 저장된 프레임의 전체 크기입니다.
• displayWidth / displayHeight: 프레임을 표시하는 데 사용해야 하는 크기입니다.
• timestamp: 마이크로초 단위의 프레임 표시 타임스탬프입니다.
• duration: 마이크로초 단위의 프레임 지속 시간입니다.

마법의 메서드: copyTo()

원시 픽셀 데이터에 접근하는 주요 메서드는 videoFrame.copyTo(destination, options)입니다. 이 비동기 메서드는 프레임의 평면 데이터를 여러분이 제공하는 버퍼로 복사합니다.

• destination: 데이터를 담을 수 있을 만큼 충분히 큰 ArrayBuffer 또는 타입 배열(예: Uint8Array)입니다.
• options: 복사할 평면과 그 메모리 레이아웃을 지정하는 객체입니다. 생략하면 모든 평면을 단일의 연속적인 버퍼에 복사합니다.

이 메서드는 프레임의 각 평면에 대해 하나씩, PlaneLayout 객체의 배열로 해석되는 Promise를 반환합니다. 각 PlaneLayout 객체는 두 가지 중요한 정보를 포함합니다:

• offset: 이 평면의 데이터가 대상 버퍼 내에서 시작되는 바이트 오프셋입니다.
• stride: 해당 평면에서 한 픽셀 행의 시작부터 다음 행의 시작까지의 바이트 수입니다.

중요 개념: Stride 대 Width

이것은 저수준 그래픽 프로그래밍을 처음 접하는 개발자들이 가장 흔하게 겪는 혼란의 원인 중 하나입니다. 각 픽셀 데이터 행이 서로 바로 뒤에 꽉 채워져 있다고 가정할 수 없습니다.

• Width는 이미지 한 행에 있는 픽셀의 수입니다.
• Stride(피치 또는 라인 스텝이라고도 함)는 메모리에서 한 행의 시작부터 다음 행의 시작까지의 바이트 수입니다.

종종 stride는 width * bytes_per_pixel보다 큽니다. 이는 CPU나 GPU에 의한 더 빠른 처리를 위해 메모리가 하드웨어 경계(예: 32 또는 64바이트 경계)에 맞춰 패딩되는 경우가 많기 때문입니다. 특정 행의 픽셀 메모리 주소를 계산할 때는 항상 스트라이드를 사용해야 합니다.

스트라이드를 무시하면 이미지가 기울어지거나 왜곡되고 잘못된 데이터 접근으로 이어집니다.

실용 예제 1: 그레이스케일 평면 접근 및 표시하기

간단하지만 강력한 예제로 시작하겠습니다. 웹상의 대부분의 비디오는 I420과 같은 YUV 형식으로 인코딩됩니다. 'Y' 평면은 사실상 이미지의 완전한 그레이스케일 표현입니다. 우리는 이 평면만 추출하여 캔버스에 렌더링할 수 있습니다.

async function displayGrayscale(videoFrame) {
  // videoFrame이 'I420' 또는 'NV12'와 같은 YUV 형식이라고 가정합니다.
  if (!videoFrame.format.startsWith('I4')) {
    console.error('이 예제는 YUV 4:2:0 평면 형식이 필요합니다.');
    videoFrame.close();
    return;
  }

  const yPlaneInfo = videoFrame.layout[0]; // Y 평면은 항상 첫 번째입니다.

  // Y 평면 데이터만 담을 버퍼를 생성합니다.
  const yPlaneData = new Uint8Array(yPlaneInfo.stride * videoFrame.codedHeight);

  // Y 평면을 우리 버퍼로 복사합니다.
  await videoFrame.copyTo(yPlaneData, {
    rect: { x: 0, y: 0, width: videoFrame.codedWidth, height: videoFrame.codedHeight },
    layout: [yPlaneInfo]
  });

  // 이제 yPlaneData에는 원시 그레이스케일 픽셀이 포함됩니다.
  // 렌더링이 필요합니다. 캔버스를 위한 RGBA 버퍼를 생성할 것입니다.
  const canvas = document.getElementById('my-canvas');
  canvas.width = videoFrame.displayWidth;
  canvas.height = videoFrame.displayHeight;
  const ctx = canvas.getContext('2d');
  const imageData = ctx.createImageData(canvas.width, canvas.height);

  // 캔버스 픽셀을 순회하며 Y 평면 데이터로 채웁니다.
  for (let y = 0; y < videoFrame.displayHeight; y++) {
    for (let x = 0; x < videoFrame.displayWidth; x++) {
      // 중요: stride를 사용하여 올바른 소스 인덱스를 찾으세요!
      const yIndex = y * yPlaneInfo.stride + x;
      const luma = yPlaneData[yIndex];

      // RGBA ImageData 버퍼의 대상 인덱스를 계산합니다.
      const rgbaIndex = (y * canvas.width + x) * 4;

      imageData.data[rgbaIndex] = luma;     // 빨강
      imageData.data[rgbaIndex + 1] = luma; // 초록
      imageData.data[rgbaIndex + 2] = luma; // 파랑
      imageData.data[rgbaIndex + 3] = 255;  // 알파
    }
  }

  ctx.putImageData(imageData, 0, 0);

  // 중요: 메모리를 해제하려면 항상 VideoFrame을 닫아야 합니다.
  videoFrame.close();
}

이 예제는 올바른 평면 레이아웃 식별, 대상 버퍼 할당, copyTo를 사용한 데이터 추출, 그리고 stride를 사용하여 데이터를 올바르게 순회하여 새 이미지를 구성하는 몇 가지 핵심 단계를 보여줍니다.

실용 예제 2: 직접 조작 (세피아 필터)

이제 직접 데이터 조작을 수행해 보겠습니다. 세피아 필터는 구현하기 쉬운 고전적인 효과입니다. 이 예제에서는 캔버스나 WebGL 컨텍스트에서 얻을 수 있는 RGBA 프레임으로 작업하는 것이 더 쉽습니다.

async function applySepiaFilter(videoFrame) {
  // 이 예제는 입력 프레임이 'RGBA' 또는 'BGRA'라고 가정합니다.
  if (videoFrame.format !== 'RGBA' && videoFrame.format !== 'BGRA') {
    console.error('세피아 필터 예제는 RGBA 프레임이 필요합니다.');
    videoFrame.close();
    return null;
  }

  // 픽셀 데이터를 담을 버퍼를 할당합니다.
  const frameDataSize = videoFrame.allocationSize();
  const frameData = new Uint8Array(frameDataSize);
  await videoFrame.copyTo(frameData);

  const layout = videoFrame.layout[0]; // RGBA는 단일 평면입니다

  // 이제 버퍼의 데이터를 조작합니다.
  for (let y = 0; y < videoFrame.codedHeight; y++) {
    for (let x = 0; x < videoFrame.codedWidth; x++) {
      const pixelIndex = y * layout.stride + x * 4; // 픽셀당 4바이트 (R,G,B,A)

      const r = frameData[pixelIndex];
      const g = frameData[pixelIndex + 1];
      const b = frameData[pixelIndex + 2];

      const tr = 0.393 * r + 0.769 * g + 0.189 * b;
      const tg = 0.349 * r + 0.686 * g + 0.168 * b;
      const tb = 0.272 * r + 0.534 * g + 0.131 * b;

      frameData[pixelIndex] = Math.min(255, tr);
      frameData[pixelIndex + 1] = Math.min(255, tg);
      frameData[pixelIndex + 2] = Math.min(255, tb);
      // 알파(frameData[pixelIndex + 3])는 변경되지 않습니다.
    }
  }

  // 수정된 데이터로 *새로운* VideoFrame을 생성합니다.
  const newFrame = new VideoFrame(frameData, {
    format: videoFrame.format,
    codedWidth: videoFrame.codedWidth,
    codedHeight: videoFrame.codedHeight,
    timestamp: videoFrame.timestamp,
    duration: videoFrame.duration
  });

  // 원본 프레임을 닫는 것을 잊지 마세요!
  videoFrame.close();

  return newFrame;
}

이는 완전한 읽기-수정-쓰기 주기를 보여줍니다: 데이터를 복사하고, 스트라이드를 사용하여 순회하고, 각 픽셀에 수학적 변환을 적용한 다음, 결과 데이터로 새로운 VideoFrame을 구성합니다. 이 새로운 프레임은 캔버스에 렌더링하거나, VideoEncoder로 보내거나, 다른 처리 단계로 전달할 수 있습니다.

성능 문제: JavaScript 대 WebAssembly (WASM)

JavaScript에서 모든 프레임에 대해 수백만 개의 픽셀(1080p 프레임은 2백만 개 이상의 픽셀, 즉 RGBA에서 8백만 개의 데이터 포인트를 가짐)을 반복하는 것은 느릴 수 있습니다. 최신 JS 엔진이 매우 빠르긴 하지만, 고해상도 비디오(HD, 4K)의 실시간 처리에는 이 접근 방식이 메인 스레드를 쉽게 압도하여 사용자 경험을 저해할 수 있습니다.

바로 이 지점에서 WebAssembly (WASM)가 필수적인 도구가 됩니다. WASM을 사용하면 C++, Rust 또는 Go와 같은 언어로 작성된 코드를 브라우저 내에서 거의 네이티브 속도로 실행할 수 있습니다. 비디오 처리를 위한 워크플로우는 다음과 같습니다:

1. 자바스크립트에서: videoFrame.copyTo()를 사용하여 원시 픽셀 데이터를 ArrayBuffer로 가져옵니다.
2. WASM으로 전달: 컴파일된 WASM 모듈에 이 버퍼에 대한 참조를 전달합니다. 이는 데이터를 복사하지 않기 때문에 매우 빠른 작업입니다.
3. WASM에서 (C++/Rust): 고도로 최적화된 이미지 처리 알고리즘을 메모리 버퍼에서 직접 실행합니다. 이는 자바스크립트 루프보다 몇 배나 빠릅니다.
4. 자바스크립트로 반환: WASM 작업이 끝나면 제어가 자바스크립트로 돌아옵니다. 그런 다음 수정된 버퍼를 사용하여 새로운 VideoFrame을 생성할 수 있습니다.

가상 배경, 객체 감지 또는 복잡한 필터와 같은 진지한 실시간 비디오 조작 애플리케이션의 경우, WebAssembly를 활용하는 것은 선택 사항이 아니라 필수입니다.

다양한 픽셀 형식 처리하기 (예: I420, NV12)

RGBA는 간단하지만, VideoDecoder로부터는 대부분 평면 YUV 형식의 프레임을 받게 될 것입니다. I420과 같은 완전 평면 형식을 처리하는 방법을 살펴보겠습니다.

I420 형식의 VideoFrame은 layout 배열에 세 개의 레이아웃 설명자를 가집니다:

• layout[0]: Y 평면 (휘도). 크기는 codedWidth x codedHeight입니다.
• layout[1]: U 평면 (색차). 크기는 codedWidth/2 x codedHeight/2입니다.
• layout[2]: V 평면 (색차). 크기는 codedWidth/2 x codedHeight/2입니다.

세 평면 모두를 단일 버퍼에 복사하는 방법은 다음과 같습니다:

async function extractI420Planes(videoFrame) {
  const totalSize = videoFrame.allocationSize({ format: 'I420' });
  const allPlanesData = new Uint8Array(totalSize);

  const layouts = await videoFrame.copyTo(allPlanesData);

  // layouts는 3개의 PlaneLayout 객체 배열입니다
  console.log('Y Plane Layout:', layouts[0]); // { offset: 0, stride: ... }
  console.log('U Plane Layout:', layouts[1]); // { offset: ..., stride: ... }
  console.log('V Plane Layout:', layouts[2]); // { offset: ..., stride: ... }

  // 이제 `allPlanesData` 버퍼 내에서 각 평면에 접근할 수 있습니다
  // 특정 오프셋과 스트라이드를 사용하여.

  const yPlaneView = new Uint8Array(
    allPlanesData.buffer,
    layouts[0].offset,
    layouts[0].stride * videoFrame.codedHeight
  );

  // 크로마 차원은 절반으로 줄어듭니다!
  const uPlaneView = new Uint8Array(
    allPlanesData.buffer,
    layouts[1].offset,
    layouts[1].stride * (videoFrame.codedHeight / 2)
  );

  const vPlaneView = new Uint8Array(
    allPlanesData.buffer,
    layouts[2].offset,
    layouts[2].stride * (videoFrame.codedHeight / 2)
  );

  console.log('Accessed Y plane size:', yPlaneView.byteLength);
  console.log('Accessed U plane size:', uPlaneView.byteLength);

  videoFrame.close();
}

또 다른 일반적인 형식은 반-평면(semi-planar)인 NV12입니다. 이것은 두 개의 평면을 가집니다: 하나는 Y를 위한 것이고, 다른 하나는 U와 V 값이 인터리브된(예: [U1, V1, U2, V2, ...]) 평면입니다. WebCodecs API는 이를 투명하게 처리합니다; NV12 형식의 VideoFrame은 단순히 layout 배열에 두 개의 레이아웃을 가집니다.

과제 및 모범 사례

이처럼 낮은 수준에서 작업하는 것은 강력하지만 책임이 따릅니다.

메모리 관리가 가장 중요합니다

VideoFrame은 상당한 양의 메모리를 보유하며, 이는 종종 자바스크립트 가비지 컬렉터의 힙 외부에서 관리됩니다. 이 메모리를 명시적으로 해제하지 않으면 브라우저 탭을 충돌시킬 수 있는 메모리 누수가 발생합니다.

프레임 사용이 끝나면 항상, 반드시 videoFrame.close()를 호출해야 합니다.

비동기적 특성

모든 데이터 접근은 비동기적입니다. 애플리케이션 아키텍처는 경쟁 조건(race condition)을 피하고 원활한 처리 파이프라인을 보장하기 위해 Promise와 async/await의 흐름을 적절하게 처리해야 합니다.

브라우저 호환성

WebCodecs는 최신 API입니다. 모든 주요 브라우저에서 지원되지만, 항상 사용 가능 여부를 확인하고 공급업체별 구현 세부 정보나 제한 사항을 인지해야 합니다. API를 사용하기 전에 기능 감지를 사용하세요.

결론: 웹 비디오의 새로운 지평

WebCodecs API를 통해 VideoFrame의 원시 평면 데이터에 직접 접근하고 조작할 수 있는 능력은 웹 기반 미디어 애플리케이션에 대한 패러다임 전환입니다. 이는 <video> 요소의 블랙박스를 제거하고 개발자에게 이전에는 네이티브 애플리케이션에만 예약되었던 세분화된 제어권을 제공합니다.

평면, 스트라이드, 색상 형식과 같은 비디오 메모리 레이아웃의 기본을 이해하고, 성능이 중요한 작업을 위해 WebAssembly의 힘을 활용함으로써, 이제 브라우저에서 직접 매우 정교한 비디오 처리 도구를 구축할 수 있습니다. 실시간 색상 보정 및 커스텀 시각 효과에서부터 클라이언트 측 머신 러닝 및 비디오 분석에 이르기까지, 가능성은 무한합니다. 웹에서의 고성능, 저수준 비디오 시대가 진정으로 시작되었습니다.